Skip to content

feat(mcp): add privacy-safe recall receipts#1031

Open
cat0825 wants to merge 2 commits into
supermemoryai:mainfrom
cat0825:cat/receipt-retrieval
Open

feat(mcp): add privacy-safe recall receipts#1031
cat0825 wants to merge 2 commits into
supermemoryai:mainfrom
cat0825:cat/receipt-retrieval

Conversation

@cat0825
Copy link
Copy Markdown

@cat0825 cat0825 commented Jun 1, 2026

Summary

Adds an optional includeReceipt flag to the MCP recall tool. When enabled, recall responses include a privacy-safe retrieval receipt in structuredContent.receipt.

The receipt helps users and maintainers debug cross-client memory retrieval without exposing raw memory text, raw queries, project names, transcripts, or private repository content.

Closes #985.

What changed

  • Added includeReceipt to the MCP recall schema.
  • Added createRetrievalReceipt() helper.
  • Receipt includes:
    • hashed query
    • hashed project/container tag
    • hashed result IDs
    • hashed returned memory/chunk content
    • result count / total
    • score buckets
    • latency
    • MCP client name/version when available
    • profile static/dynamic counts when profile recall is used
  • Added tests verifying raw private values are not exposed.

Validation

  • bunx biome check --write apps/mcp/src/server.ts apps/mcp/src/retrieval-receipt.ts apps/mcp/src/retrieval-receipt.test.ts
  • bunx vitest run src/retrieval-receipt.test.ts
  • bun run --cwd apps/mcp build:ui

bun run check-types currently fails on existing unrelated @supermemory/tools type errors.

@graphite-app graphite-app Bot requested a review from Dhravya June 1, 2026 14:23
@MaheshtheDev MaheshtheDev self-requested a review June 1, 2026 17:14
Copy link
Copy Markdown
Contributor

@ishaanxgupta ishaanxgupta left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think plain deterministic sha256 prefixes are enough to call this privacy-safe. Query text, project/container tags, memory IDs, and especially short memory content can be dictionary-guessed offline, and the same private value is linkable across receipts forever.

Plain deterministic sha256 prefixes over low-entropy values (query,
container tags, memory ids, short content) are dictionary-guessable
offline and link the same value across receipts forever. Key an HMAC
with a per-receipt random salt that is never emitted, so tokens cannot
be precomputed or correlated across receipts while equality is still
preserved within a single receipt for debugging.
@cat0825
Copy link
Copy Markdown
Author

cat0825 commented Jun 3, 2026

Good catch, you're right that a plain deterministic SHA-256 prefix isn't privacy-safe for these inputs. I've reworked the hashing in createRetrievalReceipt:

  • Each receipt now generates a fresh 32-byte random salt and keys an HMAC-SHA256 with it. The salt is never emitted in the receipt.
  • Without the salt, the low-entropy values (query, container/project tag, memory IDs, short content) can no longer be dictionary-guessed or precomputed offline.
  • Because the salt is regenerated per receipt, the same private value produces a different token every time, so values are no longer linkable across receipts.
  • Equality is still preserved within a single receipt (e.g. duplicate IDs/content in one result set), which is what the debugging use case needs.

hashAlgorithm is now reported as hmac-sha256-ephemeral-salt-prefix-16, and I added a regression test covering both properties (intra-receipt equality and cross-receipt non-linkability). Let me know if you'd prefer a different trade-off here, e.g. dropping content hashes entirely or making the receipt opt-in behind a server-side flag rather than a per-call param.

@cat0825 cat0825 requested a review from ishaanxgupta June 3, 2026 11:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Expose privacy-safe memory retrieval receipts

2 participants